home *** CD-ROM | disk | FTP | other *** search
/ SGI Hot Mix 17 / Hot Mix 17.iso / HM17_SGI / research / lib / obsolete / cw_savestate.pro < prev    next >
Text File  |  1997-07-08  |  7KB  |  196 lines
  1. ; $Id: cw_savestate.pro,v 1.3 1997/01/15 04:02:19 ali Exp $
  2. ;
  3. ; Copyright (c) 1992-1997, Research Systems, Inc.  All rights reserved.
  4. ;    Unauthorized reproduction prohibited.
  5. ;+
  6. ; NAME:
  7. ;    CW_SAVESTATE
  8. ;
  9. ; PURPOSE:
  10. ;      --------------------------------------------------------------
  11. ;      | This is an obsolete routine. New applications should       |
  12. ;      | be written to use the NO_COPY keyword to WIDGET_CONTROL to |
  13. ;      | efficiently maintain widget state in a UVALUE.)            |
  14. ;      --------------------------------------------------------------
  15. ;
  16. ;    Compound widgets cannot use a COMMON block to keep their state
  17. ;    information in because that would preclude having more than
  18. ;    one at a time. One solution is to keep their state as a
  19. ;    structure in the UVALUE of one of the widgets in the cluster.
  20. ;    Once this is done, it is then possible to use a COMMON block to
  21. ;    cache the most recently used state. This is the scheme implemented
  22. ;    by the CW_SAVESTATE and CW_LOADSTATE procedures. CW_LOADSTATE is
  23. ;    called by the main compound widget function that creates the
  24. ;    widgets. It stores the state in the UVALUE of the first child.
  25. ;    Other functions that require the state call CW_LOADSTATE to
  26. ;    ensure that the correct state is present.
  27. ;
  28. ; CATEGORY:
  29. ;    Compound widgets.
  30. ;
  31. ; CALLING SEQUENCE:
  32. ;    Creation function:
  33. ;
  34. ;        COMMON CW_XYZ_BLK, state_base, state_stash, state
  35. ;        CW_SAVESTATE, base, state_base, new_state
  36. ;
  37. ;    Other routines:
  38. ;
  39. ;        COMMON CW_XYZ_BLK, state_base, state_stash, state
  40. ;        CW_LOADSTATE, base, state_base, state_stash, state
  41. ;
  42. ;    If the other routines are called heavily, the following is
  43. ;    a more efficient way to call CW_LOADSTATE:
  44. ;
  45. ;        COMMON CW_XYZ_BLK, state_base, state_stash, state
  46. ;        if (base ne state_base) then $
  47. ;            CW_LOADSTATE, base, state_base, state_stash, state
  48. ;
  49. ;    Note that the COMMON block must be defined in every routine that
  50. ;    calls these procedures. The name of the COMMON block is unique
  51. ;    to each compound widget, but the names of the variables inside
  52. ;    the COMMON must be as shown.
  53. ;
  54. ; INPUTS:
  55. ;   CW_SAVESTATE:
  56. ;    BASE - The ID of the base widget of the cluster.
  57. ;    STATE_BASE - The state_base variable from the COMMON block.
  58. ;    NEW_STATE - The new state that should be saved in the UVALUE.
  59. ;
  60. ;        NOTE: This is not the same as the STATE variable from
  61. ;          the COMMON block. Confusing them can result in
  62. ;          corrupting the state of an already existing instance
  63. ;          of the compound widget.
  64. ;
  65. ;   CW_LOADSTATE:
  66. ;    BASE - The ID of the base widget of the cluster.
  67. ;    STATE_BASE - The STATE_BASE variable from the COMMON block.
  68. ;    STATE_STASH - The STATE_STASH variable from the COMMON block.
  69. ;    STATE - The STATE variable from the COMMON block.
  70. ;
  71. ; KEYWORD PARAMETERS:
  72. ;    None.
  73. ;
  74. ; OUTPUTS:
  75. ;    No explicit outputs.
  76. ;
  77. ; COMMON BLOCKS:
  78. ;    None in these routines, but the calling routines must have the
  79. ;    per compound widget class COMMON discussed above.
  80. ;
  81. ; SIDE EFFECTS:
  82. ;    CW_SAVESTATE saves the new state for a freshly created compound
  83. ;    widget.
  84. ;
  85. ;    CW_LOADSTATE flushes the current state from the compound widget
  86. ;    COMMON block and loads the state for the specified widget.
  87. ;
  88. ; RESTRICTIONS:
  89. ;
  90. ;      --------------------------------------------------------------
  91. ;      | This is an obsolete routine. New applications should       |
  92. ;      | be written to use the NO_COPY keyword to WIDGET_CONTROL to |
  93. ;      | efficiently maintain widget state in a UVALUE.)            |
  94. ;      --------------------------------------------------------------
  95. ;
  96. ;    These routines use the UVALUE of the first child of the compound
  97. ;    widget base. Hence, the compound widget should not make use
  98. ;    of this UVALUE or confusion will result.
  99. ;
  100. ;    One solution to this problem is to include an extra base
  101. ;    between the top base and the rest of the widgets. For example:
  102. ;
  103. ;        OUTER_BASE = WIDGET_BASE()
  104. ;        INNER_BASE = WIDGET_BASE(OUTER_BASE)
  105. ;        OTHER_WIDGET = WIDGET_BUTTON(INNER_BASE)
  106. ;        ...
  107. ;
  108. ; PROCEDURE:
  109. ;    Every compound widget that uses these procedures keeps the
  110. ;    most recently accessed state in the UVALUE of the first child
  111. ;    of the compound widget base. These procedures load and unload
  112. ;    the states for each instance of compound widget as needed.
  113. ;
  114. ; EXAMPLE:
  115. ;
  116. ;    Here is the framework for a compound widget at its event function
  117. ;
  118. ;    function CW_XYZ_EVENT, ev
  119. ;
  120. ;      COMMON CW_XYZ_BLK, state_base, state_stash, state
  121. ;      CW_LOADSTATE, ev.handler, state_base, state_stash, state
  122. ;
  123. ;        ; Event processing goes here. The widget state is
  124. ;        ; contained in the variable state.
  125. ;    end
  126. ;
  127. ;    function CW_XYZ, parent
  128. ;
  129. ;      COMMON CW_XYZ_BLK, state_base, state_stash, state
  130. ;         ;
  131. ;      base = widget_base()
  132. ;
  133. ;        ; Other widgets are created here
  134. ;
  135. ;      new_state = ...    ; The new state is widget dependent
  136. ;
  137. ;      CW_SAVESTATE, base, state_base, new_state
  138. ;      return, base
  139. ;    end
  140. ;
  141. ; MODIFICATION HISTORY:
  142. ;    AB, June 1992
  143. ;-
  144.  
  145.  
  146. pro CW_SAVESTATE, base, state_base, new_state
  147.   ; Load the new_state variable into the user value of the first child
  148.   ; of base.
  149.  
  150.   COMMON CW_SAVSTAT_OBS, obsolete
  151.  
  152.   if not KEYWORD_SET(obsolete) then begin
  153.     obsolete = 1
  154.     message,/INFO,"The CW_SAVESTATE and CW_LOADSTATE user library routines are obsolete. They are superceeded by the NO_COPY keyword to the WIDGET_CONTROL procedure."
  155.   endif
  156.  
  157.  
  158.  
  159.   ; There are many reasons why we might want to invalidate the cache
  160.   ; by setting state_base to zero. The logic can get a bit tricky.
  161.   ;
  162.   ;    - state_base is undefined, meaning that this is the first
  163.   ;       savestate for this compound widget class.
  164.   ;
  165.   ;    - state_base is the same as our new widget, meaning that
  166.   ;      the state in the common block is for a previous incarnation
  167.   ;       of a widget of this class headed by a widget with the
  168.   ;       same ID. (A very rare case)
  169.   ;
  170.   ;    - state_base is an invalid ID, meaning the widget owning
  171.   ;       the current state has died and not been reused. (This is likely)
  172.   ;
  173.   ;    - state_base is valid, but has a different event handler than
  174.   ;      the new ID. In this case, the widget owning the current state
  175.   ;       has died and has been since reused, but in a different
  176.   ;       application. The assumption here is that two widgets
  177.   ;       with non-null event handlers that agree must be different
  178.   ;      instantiations of the same class. (This is likely)
  179.   ;
  180.   ; Note: IDL's IF statement does not do short circuit evaluation, hence
  181.   ;       the strange looking structure of this code.
  182.   if (n_elements(state_base) eq 0) then begin
  183.       state_base=0L
  184.   endif else if (base eq state_base) then begin
  185.       state_base = 0L
  186.   endif else if (not widget_info(state_base, /VALID)) then begin
  187.       state_base = 0L
  188.   endif else if (widget_info(base, /EVENT_FUNC) $
  189.                  ne widget_info(state_base, /EVENT_FUNC)) then begin
  190.       state_base = 0L
  191.   endif
  192.  
  193.   WIDGET_CONTROL, WIDGET_INFO(base, /CHILD), set_uvalue=new_state
  194.  
  195. end
  196.